/*
 * Copyright 2009 SHOP.COM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.shop.opensocial.mediated.types;

import java.util.Date;
import java.util.List;

/**
 * Independent mediator for corresponding OpenSocial type
 *
 * @author Jordan Zimmerman
 */
public interface PersonMediator
{
	/**
	 * Enumeration of genders.
	 */
	public enum Gender
	{
		FEMALE,
		MALE
	}

	/**
	 * The display name for the user.
	 *
	 * @return the display name
	 */
	public String getDisplayName();

	/**
	 * Get a general statement about the person, specified as a string. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the value of aboutMe
	 */
	public String getAboutMe();

	/**
	 * Get the list of online accounts held by this person.
	 *
	 * @return a list of Account objects
	 */
	public List<AccountMediator> getAccounts();

	/**
	 * Get the person's favorite activities, specified as an List of strings. Container support for
	 * this field is OPTIONAL.
	 *
	 * @return list of activities.
	 */
	public List<String> getActivities();

	/**
	 * Get addresses associated with the person, specified as an List of Address objects. Container
	 * support for this field is OPTIONAL.
	 *
	 * @return a List of address objects
	 */
	public List<AddressMediator> getAddresses();

	/**
	 * Get the person's age, specified as a number. Container support for this field is OPTIONAL.
	 *
	 * @return the persons age
	 */
	public Integer getAge();

	/**
	 * Get the person's date of birth, specified as a {@link Date} object. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the person's data of birth
	 */
	public Date getBirthday();

	/**
	 * Get the person's body characteristics, specified as an BodyType. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the BodyType
	 */
	public BodyTypeMediator getBodyType();

	/**
	 * Get the person's favorite books, specified as an List of strings. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return list of books as strings
	 */
	public List<String> getBooks();

	/**
	 * Get the person's favorite cars, specified as an List of strings. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the persons favorite cars
	 */
	public List<String> getCars();

	/**
	 * Get a description of the person's children, specified as a string. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the persons children
	 */
	public String getChildren();

	/**
	 * Get the person's current location, specified as an {@link AddressMediator}. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the persons current location
	 */
	public AddressMediator getCurrentLocation();

	public enum Drinker
	{
		/**
		 * Heavy drinker.
		 */
		HEAVILY,
		/**
		 * non drinker.
		 */
		NO,
		/**
		 * occasional drinker.
		 */
		OCCASIONALLY,
		/**
		 * has quit drinking.
		 */
		QUIT,
		/**
		 * in the process of quitting.
		 */
		QUITTING,
		/**
		 * regular drinker.
		 */
		REGULARLY,
		/**
		 * drinks socially.
		 */
		SOCIALLY,
		/**
		 * yes, a drinker of alchhol.
		 */
		YES
	}

	/**
	 * Get the person's drinking status
	 * Container support for this field is OPTIONAL.
	 *
	 * @return the persons drinking status
	 */
	public Drinker getDrinker();

	/**
	 * Get the person's Emails associated with the person.
	 * Container support for this field is OPTIONAL.
	 *
	 * @return a list of the person's emails
	 */
	public List<ListFieldMediator> getEmails();

	/**
	 * Get the person's ethnicity, specified as a string. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return the person's ethnicity
	 */
	public String getEthnicity();

	/**
	 * Get the person's thoughts on fashion, specified as a string. Container support for this field
	 * is OPTIONAL.
	 *
	 * @return the person's thoughts on fashion
	 */
	public String getFashion();

	/**
	 * Get the person's favorite food, specified as an List of strings. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the person's favorite food
	 */
	public List<String> getFood();

	/**
	 * Get a person's gender, specified as an {@link Gender}.
	 *
	 * @return the person's gender
	 */
	public Gender getGender();

	/**
	 * Get a description of when the person is happiest, specified as a string. Container support for
	 * this field is OPTIONAL.
	 *
	 * @return a description of when the person is happiest
	 */
	public String getHappiestWhen();

	/**
	 * Get if the person has used the current app. Container support for this field is OPTIONAL.
	 * Has app needs to take account of the context of the application that is performing the
	 * query on this person object.
	 *
	 * @return true the current app has been used
	 */
	public Boolean getHasApp();

	/**
	 * Get a person's favorite heroes, specified as an Array of strings. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return a list of the person's favorite heroes
	 */
	public List<String> getHeroes();

	/**
	 * Get the person's thoughts on humor, specified as a string. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return the person's thoughts on humor
	 */
	public String getHumor();

	/**
	 * Get A string ID that can be permanently associated with this person. Container support for this
	 * field is REQUIRED.
	 *
	 * @return the permanent ID of the person
	 */
	public String getId();

	/**
	 * Get a list of Instant messaging address for this Person. No official canonicalization rules
	 * exist for all instant messaging addresses, but Service Providers SHOULD remove all whitespace
	 * and convert the address to lowercase, if this is appropriate for the service this IM address is
	 * used for. Instead of the standard Canonical Values for type, this field defines the following
	 * Canonical Values to represent currently popular IM services: aim, gtalk, icq, xmpp, msn, skype,
	 * qq, and yahoo.
	 *
	 * @return A list of IM addresses
	 */
	public List<ListFieldMediator> getIms();

	/**
	 * Get the person's interests, hobbies or passions, specified as an List of strings. Container
	 * support for this field is OPTIONAL.
	 *
	 * @return the person's interests, hobbies or passions
	 */
	public List<String> getInterests();

	/**
	 * Get the Person's favorite jobs, or job interests and skills, specified as a string. Container
	 * support for this field is OPTIONAL
	 *
	 * @return the Person's favorite jobs, or job interests and skills
	 */
	public String getJobInterests();

	/**
	 * Get a List of the languages that the person speaks as ISO 639-1 codes, specified as an List of
	 * strings. Container support for this field is OPTIONAL.
	 *
	 * @return a List of the languages that the person speaks
	 */
	public List<String> getLanguagesSpoken();

	/**
	 * The time this person was last updated.
	 *
	 * @return the last update time
	 */
	public Date getUpdated();

	/**
	 * Get a description of the person's living arrangement, specified as a string. Container support
	 * for this field is OPTIONAL.
	 *
	 * @return a description of the person's living arrangement
	 */
	public String getLivingArrangement();

	public enum LookingFor
	{
		/**
		 * Interested in dating.
		 */
		DATING,
		/**
		 * Looking for friends.
		 */
		FRIENDS,
		/**
		 * Looking for a relationship.
		 */
		RELATIONSHIP,
		/**
		 * Just want to network.
		 */
		NETWORKING,
		/** */
		ACTIVITY_PARTNERS,
		/** */
		RANDOM
	}

	/**
	 * Get a person's statement about who or what they are looking for, or what they are interested in
	 * meeting people for.
	 * Container support for this field is OPTIONAL.
	 *
	 * @return person's statement about who or what they are looking for
	 */
	public List<LookingFor> getLookingFor();

	/**
	 * Get the Person's favorite movies, specified as an List of strings. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return the Person's favorite movies
	 */
	public List<String> getMovies();

	/**
	 * Get the Person's favorite music, specified as an List of strings Container support for this
	 * field is OPTIONAL.
	 *
	 * @return Person's favorite music
	 */
	public List<String> getMusic();

	/**
	 * Get the person's name Container support for this field is REQUIRED.
	 *
	 * @return the person's name
	 */
	public NameMediator getName();

	public enum NetworkPresence
	{
		/**
		 * Currently Online.
		 */
		ONLINE,
		/**
		 * Currently Offline.
		 */
		OFFLINE,
		/**
		 * Currently online but away.
		 */
		AWAY,
		/**
		 * In a chat or available to chat.
		 */
		CHAT,
		/**
		 * Online, but don't disturb.
		 */
		DND,
		/**
		 * Gone away for a longer period of time.
		 */
		XA
	}

	/**
	 * Get the person's current network status.
	 * Container support for this field is OPTIONAL.
	 *
	 * @return the person's current network status
	 */
	public NetworkPresence getNetworkPresence();

	/**
	 * Get the person's nickname. Container support for this field is REQUIRED.
	 *
	 * @return the person's nickname.
	 */
	public String getNickname();

	/**
	 * Get a list of current or past organizational affiliations of this Person.
	 *
	 * @return a list of Organization objects
	 */
	public List<OrganizationMediator> getOrganizations();

	/**
	 * Get a description of the person's pets Container support for this field is OPTIONAL.
	 *
	 * @return a description of the person's pets
	 */
	public String getPets();

	/**
	 * Get the Phone numbers associated with the person.
	 *
	 * @return the Phone numbers associated with the person
	 */
	public List<ListFieldMediator> getPhoneNumbers();

	/**
	 * URL of a photo of this person. The value SHOULD be a canonicalized URL, and MUST point to an
	 * actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a web page containing an
	 * image. Service Providers MAY return the same image at different sizes, though it is recognized
	 * that no standard for describing images of various sizes currently exists. Note that this field
	 * SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile
	 * photos of the contact suitable for display when describing the contact.
	 *
	 * @return a list of Photos
	 */
	public List<ListFieldMediator> getPhotos();

	/**
	 * Get the Person's political views, specified as a string. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return the Person's political views
	 */
	public String getPoliticalViews();

	/**
	 * Get the Person's profile song, specified as an {@link UrlMediator}. Container support for this field
	 * is OPTIONAL.
	 *
	 * @return the Person's profile song
	 */
	public UrlMediator getProfileSong();

	/**
	 * Get the Person's profile video. Container support for this field is OPTIONAL.
	 *
	 * @return the Person's profile video
	 */
	public UrlMediator getProfileVideo();

	/**
	 * Get the person's favorite quotes Container support for this field is OPTIONAL.
	 *
	 * @return the person's favorite quotes
	 */
	public List<String> getQuotes();

	/**
	 * Get the person's relationship status. Container support for this field is OPTIONAL.
	 *
	 * @return the person's relationship status
	 */
	public String getRelationshipStatus();

	/**
	 * Get the person's relgion or religious views. Container support for this field is OPTIONAL.
	 *
	 * @return the person's relgion or religious views
	 */
	public String getReligion();

	/**
	 * Get the person's comments about romance. Container support for this field is OPTIONAL.
	 *
	 * @return the person's comments about romance,
	 */
	public String getRomance();

	/**
	 * Get what the person is scared of Container support for this field is OPTIONAL.
	 *
	 * @return what the person is scared of
	 */
	public String getScaredOf();

	/**
	 * Get the person's sexual orientation. Container support for this field is OPTIONAL.
	 *
	 * @return the person's sexual orientation
	 */
	public String getSexualOrientation();

	public enum Smoker
	{
		/**
		 * A heavy smoker.
		 */
		HEAVILY,
		/**
		 * Non smoker.
		 */
		NO,
		/**
		 * Smokes occasionally.
		 */
		OCCASIONALLY,
		/**
		 * Has quit smoking.
		 */
		QUIT,
		/**
		 * in the process of quitting smoking.
		 */
		QUITTING,
		/**
		 * regular smoker, but not a heavy smoker.
		 */
		REGULARLY,
		/**
		 * smokes socially.
		 */
		SOCIALLY,
		/**
		 * yes, a smoker.
		 */
		YES
	}

	/**
	 * Get the person's smoking status. Container support for this field is OPTIONAL.
	 *
	 * @return the person's smoking status
	 */
	public Smoker getSmoker();

	/**
	 * Get the person's favorite sports. Container support for this field is OPTIONAL.
	 *
	 * @return the person's favorite sports
	 */
	public List<String> getSports();

	/**
	 * Get the person's status, headline or shoutout. Container support for this field is OPTIONAL.
	 *
	 * @return the person's status, headline or shoutout
	 */
	public String getStatus();

	/**
	 * Get arbitrary tags about the person. Container support for this field is OPTIONAL.
	 *
	 * @return arbitrary tags about the person.
	 */
	public List<String> getTags();

	/**
	 * Get the Person's time zone, specified as the difference in minutes between Greenwich Mean Time
	 * (GMT) and the user's local time. Container support for this field is OPTIONAL.
	 *
	 * @return the Person's time zone
	 */
	public Long getUtcOffset();

	/**
	 * Get the person's turn offs. Container support for this field is OPTIONAL.
	 *
	 * @return the person's turn offs
	 */
	public List<String> getTurnOffs();

	/**
	 * Get the person's turn ons. Container support for this field is OPTIONAL.
	 *
	 * @return the person's turn ons
	 */
	public List<String> getTurnOns();

	/**
	 * Get the person's favorite TV shows. Container support for this field is OPTIONAL.
	 *
	 * @return the person's favorite TV shows.
	 */
	public List<String> getTvShows();

	/**
	 * Get the URLs related to the person, their webpages, or feeds Container support for this field
	 * is OPTIONAL.
	 *
	 * @return the URLs related to the person, their webpages, or feeds
	 */
	public List<UrlMediator> getUrls();

	/**
	 * @return true if this person object represents the owner of the current page.
	 */
	public boolean getIsOwner();

	/**
	 * Returns true if this person object represents the currently logged in user.
	 *
	 * @return true if the person accessing this object is a viewer.
	 */
	public boolean getIsViewer();

	// Proxied fields

	/**
	 * Get the person's profile URL. This URL must be fully qualified. Relative URLs will not work in
	 * gadgets. This field MUST be stored in the urls list with a type of "profile".
	 * <p/>
	 * Container support for this field is OPTIONAL.
	 *
	 * @return the person's profile URL
	 */
	public String getProfileUrl();

	/**
	 * Get the person's photo thumbnail URL, specified as a string. This URL must be fully qualified.
	 * Relative URLs will not work in gadgets.
	 * This field MUST be stored in the photos list with a type of "thumbnail".
	 * <p/>
	 * Container support for this field is OPTIONAL.
	 *
	 * @return the person's photo thumbnail URL
	 */
	public String getThumbnailUrl();
}
